<!DOCTYPE html>
<html>
  <head>
    <meta charset='utf-8'/>
    <title>Shadow DOM</title>
    <script src='https://www.w3.org/Tools/respec/respec-w3c-common' async class='remove'></script>
    <script class='remove'>
      window.respecConfig = {
          specStatus: "ED",
          shortName: "shadow-dom",
          edDraftURI: "https://w3c.github.io/webcomponents/spec/shadow/",
          editors: [{ name: "nobody is currently editing this specification" }],
          license: "w3c-software-doc",
          localBiblio: {
              "EDITING": {
                  title: "HTML Editing APIs",
                  href: "https://dvcs.w3.org/hg/editing/raw-file/tip/editing.html",
                  authors:  ["Aryeh Gregor"]
              }
          }
      };
    </script>
  </head>
  <body>
    <section id='abstract'>
      <p>
        This specification contains leftover shadow DOM-related definitions which are not yet given a more permanent home in other specifications.
      </p>

      <details class="annoying-warning" open>
        <summary>Not an active specification</summary>

        Most of the Shadow DOM specification has been upstreamed to <cite>DOM</cite> [[DOM]], <cite>HTML</cite> [[HTML]], <cite>CSS Scoping</cite> [[css-scoping-1]],
        <cite>UI Events</cite> [[uievents]], and other relevant specifications. What remains here is stuff which has not yet been properly vetted and integrated into the specification ecosystem.
        As such, the contents here are not fully reliable.
        See <a href="https://github.com/w3c/webcomponents/issues/661">Issue #377</a> for details.
      </details>
    </section>

    <section id='sotd'>
    </section>

    <section class='normative'>
      <h2>User Interaction</h2>

      <section>
        <h3>Ranges and Selections</h3>

        <p>
          Selection [[!EDITING]] is not defined. Implementation should do their best to do what's best for them. Here's one possible, admittedly naive way:
        </p>

        <p>Since nodes which are in the different node trees never have the same root, there may never exist a valid DOM range that spans multiple node trees.</p>

        <p>Accordingly, selections may only exist within one node tree, because they are defined by a single range. The selection, returned by the <code>window.getSelection()</code> method never returns a selection within a shadow tree.</p>

        <p>The <code>getSelection()</code> method of the shadow root object returns the current selection in this shadow tree.</p>
      </section>

      <section class='normative'>
        <h3>Editing</h3>

        <p>The value of the <code>contenteditable</code> attribute <strong>must not</strong> propagate from shadow host to its shadow trees.</p>
      </section>

      <section>
        <h3>Assistive Technology</h3>

        <p>User agents with assistive technology traverse the flat tree, and thus enable full use of WAI-ARIA [[!WAI-ARIA]] semantics in the shadow trees.</p>

      </section>

      <section>
        <h3>Hit Testing</h3>

        <p>
          When a text node is a child node of a shadow root, a hit testing <strong>must</strong> target the shadow host if the text node is the result of the hit testing.
        </p>
        <p>
          User-agent mouse events <strong>must</strong> be targeted to the parent node in the flat tree of a text node if the topmost event target is the text node.
        </p>
        <p class="note">
          This section eventually needs to be part of some general hit testing specification.
        </p>
      </section>

    </section>

    <section class='normative'>
      <h2>HTML Elements in Shadow Trees</h2>

      <section>
        <h3>Inertness of HTML Elements in a shadow tree</h3>

        <p>Comparatively, a shadow tree can be seen as somewhere between <em>just part of a document</em> and itself being a document fragment. Since it is rendered, a shadow tree aims to retain the traits of a typical tree in a document. At the same time, it is an encapsulation abstraction, so it has to avoid affecting the document tree. Thus, the HTML elements <strong>must</strong> behave as specified [[!HTML]] in the shadow trees, with a few exceptions.</p>

        <p class="note">
          According to the [[!HTML]], some HTML Elements would have different behavior if they participate in a shadow tree, instead of a document tree,
          because their definitions require the elements to be in a document as a necessary condition for them to work.
          In other words, they shouldn't work if they participate in a shadow tree, even when they are in a shadow-including document.
          We must fill this gap because we expect that most of HTML Elements behave in the same way as in a document, as long as they are in a shadow-including document.
          See W3C <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=26365">Bug 26365</a> and <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=27406">Bug 27406</a> for the details.
          The following is the tentative summary of the discussions in the W3C bugs. We, however, haven't covered all HTML Elements and their behaviors here yet.
          For HTML Elements which are not explicitly stated here, they should *work* even in a shadow tree.
          We are trying to update [[!HTML]] itself, instead of having monkey patches here.
          If [[!HTML]] explains an element's behavior explicitly, it should be honored, instead of this section.
        </p>
        <p>
          Some HTML Elements are classified into the following categories:
        </p>
        <ul>
          <li>
            <p>
              <dfn>Inert in a shadow tree</dfn>:
            </p>
            <p>
              A subset of HTML elements which <strong>must</strong> behave as inert, or not part of the document tree, if they participate in a shadow tree.
              This is consistent how the HTML elements would behave in a document fragment.
            </p>
            <p>
              The following HTML elements <strong>must</strong> be classified to this category:
            </p>
            <ul>
              <li><code>base</code></li>
              <li><code>link</code></li>

              <li><code>meta</code></li>
            </ul>
            <p class="note">
              &lt;link rel="stylesheet"&gt; is now supported in a shadow tree (<a href="https://github.com/whatwg/html/commit/43c57866c2bbc20dc0deb15a721a28cbaad2140c">HTML Standard</a>).
              For other cases, the discussion is on-going at <a href="https://github.com/w3c/webcomponents/issues/628">Issue #628</a>.
            </p>
          </li>
          <li>
            <p>
              <dfn>Inert unless being rendered</dfn>:
            </p>
            <p>
              A subset of HTML elements which <strong>must</strong> behave as inert, or not part of the document tree,
              unless they are being rendered.
              In other words, if they don't participate in a document flat tree, they <strong>must</strong> behave as inert.
            </p>
            <p>
              The following HTML elements <strong>must</strong> be classified to this category:
            </p>
            <ul>
              <li><code>applet</code></li>
              <li><code>embed</code></li>
              <li><code>object</code></li>
            </ul>
            <p class="note">
              For example, suppose that an <code>object</code> element is a child node of a shadow host, but the <code>object</code> element is not assigned to a slot.
              In this case, according to the flat tree children calculation algorithm,
              this element never participate in a document flat tree.
              Therefore, this element is inert because this element is not being rendered. .
            </p>
          </li>
        </ul>
      </section>

      <section>
        <h3>Attributes</h3>

        <p>When [[!HTML]] defines the processing algorithms to traverse trees for the following attributes, they <strong>must</strong> use the flat tree.
        <ul>
          <li><code>dir</code></li>
          <li><code>draggable</code></li>
          <li><code>dropzone</code></li>
          <li><code>hidden</code></li>
          <li><code>lang</code> and <code>xml:lang</code></li>
          <li><code>spellcheck</code></li>
          <li><code>title</code></li>
        </ul>

        <p class="note"><code>role</code> and <code>ARIA</code> are defined in <a href="#assistive-technology">Assistive Technology</a>.</p>
      </section>

      <section>
        <h3>Other Clarifications</h3>

        <p class="note">
          This section is used to state what needs to be clarified.
          Each clarification will be upstreamed to the HTML Standard or other specifications, eventually, if required.
        </p>

        <p>
          Style elements inside a shadow tree <strong>must</strong> not be able to set the preferred style sheet set for the document tree.
          Style elements inside a shadow tree should still be applied if it has a <code>title</code> attribute not matching the preferred style sheet set
          of the document tree.
          See <a href="https://github.com/w3c/webcomponents/issues/391">Issue #391</a>.
        </p>

        <p>
          An iframe in a shadow tree <strong>must</strong> not have any effect on <code>window.history</code> neither <code>window.frames</code>.
          See <a href="https://github.com/w3c/webcomponents/issues/184">Issue #184</a>.
        </p>

        <p>
          <code>:root</code> pseudo class does not match any element if the rule is used in a shadow tree.
        </p>
      </section>

    </section>

    <section class='normative'>
      <h2>Elements and DOM interfaces</h2>

      <section>
        <h3>Extensions to the <code><a href="https://dom.spec.whatwg.org/#documentorshadowroot">DocumentOrShadowRoot</a></code> Mixin</h3>

        <pre class='idl'>
          partial interface DocumentOrShadowRoot {
            Selection? getSelection ();
            Element? elementFromPoint(double x, double y);
            sequence&lt;Element&gt; elementsFromPoint(double x, double y);
            CaretPosition? caretPositionFromPoint(double x, double y);
          };
        </pre>

        <ul class="note">
          <li>
            These methods and attributes are defined in the similar way as currently defined in Document,
            considering only the current node tree.
          </li>
          <li>
            Regarding <code>elementFromPoint</code> and <code>elementsFromPoints</code>, they should return the result of running the retargeting algorithm with context object and the original result as input.
          </li>
          <li>
            We should remove these methods and attributes from Document when this section is upstreamed.
          </li>
        </ul>
      </section>


    <section class="appendix">
      <h2>Acknowledgments</h2>

      <p><span class="vcard">David Hyatt</span> developed <a href="http://dev.w3.org/2006/xbl2/">XBL 1.0</a>, and <span class="vcard">Ian Hickson</span> co-wrote <a href="http://dev.w3.org/2006/xbl2/">XBL 2.0</a>. These documents provided tremendous insight into the problem of functional encapsulation and greatly influenced this specification.</p>

      <p><span class="vcard">Alex Russell</span> and his considerable forethought triggered a new wave of enthusiasm around the subject of shadow DOM and how it can be applied practically on the Web.</p>

      <p><span class="vcard">Dominic Cooney</span>, <span class="vcard">Hajime Morrita</span>, and <span class="vcard">Roland Steiner</span> worked tirelessly to scope the problem of functional encapsulation within the confines of the Web platform and provided a solid foundation for this document.</p>

      <p>The editor would also like to thank <span class="vcard">Alex Komoroske</span>, <span class="vcard">Anne van Kesteren</span>, <span class="vcard">Brandon Payton</span>, <span class="vcard">Brian Kardell</span>, <span class="vcard">Darin Fisher</span>, <span class="vcard">Eric Bidelman</span>, <span class="vcard">Deepak Sherveghar</span>, <span class="vcard">Edward O'Connor</span>, <span class="vcard">Elisée Maurer</span>, <span class="vcard">Elliott Sprehn</span>, <span class="vcard">Erik Arvidsson</span>, <span class="vcard">Glenn Adams</span>, <span class="vcard">Jonas Sicking</span>, <span class="vcard">Koji Ishii</span>, <span class="vcard">Malte Ubl</span>, <span class="vcard">Mike Taylor</span>, <span class="vcard">Oliver Nightingale</span>, <span class="vcard">Olli Pettay</span>, <span class="vcard">Rafael Weinstein</span>, <span class="vcard">Richard Bradshaw</span>, <span class="vcard">Ruud Steltenpool</span>, <span class="vcard">Sam Dutton</span>, <span class="vcard">Sergey G. Grekhov</span>, <span class="vcard">Shinya Kawanaka</span>, <span class="vcard">Tab Atkins</span>, <span class="vcard">Takashi Sakamoto</span>, and <span class="vcard">Yoshinori Sano</span> for their comments and contributions to this specification.</p>
    </section>

  </body>
</html>
